Feat/TO-540: Add passkey controller by tanguyenvn · Pull Request #8422 · MetaMask/core

tanguyenvn · 2026-04-10T04:22:29Z

Explanation

Add passkey-controller. The idea is that:

UI will import @simplewebauthn/browser
controller mimics types of @simplewebauthn/server (as the controller can be used in both browser worker and mobile react native )
We'll follow same approach as simplewebauthn

# CORE
PasskeyController {
  state: {passkeyRecord: ...}
  function getRegistrationOptions() {...}
  function getAuthenticationOptions() {...}
  function completeRegistration(registrationResponse) {...}
  function unwrapVaultEncryptionKey(authResponse) {...}
}

# UI
1. REGISTER FLOW
- registrationOptions = requestBackground('getRegistrationOptions')
- response = startRegistration(registrationOptions)
- requestBackground('completeRegistration', response)

2. UNLOCK FLOW
- authOptions = requestBackground('getAuthenticationOptions')
- response = startAuthentication(authOptions)
- requestBackground('unwrapVaultEncryptionKey', response)

References

Checklist

I've updated the test suite for new or updated code as appropriate
I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
I've communicated my changes to consumers by updating changelogs for packages I've changed
I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

Note

High Risk
Introduces a new security-critical controller that implements WebAuthn verification and cryptographic key wrapping/unwrapping for vault keys; mistakes could impact authentication integrity or key recovery.

Overview
Adds a new @metamask/passkey-controller package implementing a PasskeyController to orchestrate passkey enrollment, authentication, vault-key wrapping/unwrapping, and key-rotation (renewVaultKeyProtection), including persisted passkeyRecord state and lifecycle resets via clearState/removePasskey.

The package includes self-contained WebAuthn response verification (challenge/origin/RP ID hash, flags, signature verification for EC/EdDSA via @noble/curves with RSA via Web Crypto, and counter monotonicity) plus adaptive key derivation (PRF-extension vs userHandle) and AES-256-GCM + HKDF utilities; comprehensive Jest coverage and documentation are added.

Repo wiring updates include new build refs (tsconfig.build.json), ownership mapping (teams.json), and new dependencies in yarn.lock (notably @levischuck/tiny-cbor and updated @noble/curves range).

^{Reviewed by Cursor Bugbot for commit 6f7b1c7. Bugbot is set up for automated code reviews on this repo. Configure here.}

…n options

…from simplewebauthn

…on options

cursor · 2026-04-16T11:37:55Z

+      encKey,
+    );
+
+    this.#authenticationSession = null;


Auth Session Not Cleared After Failed Decryption

Medium Severity

In both retrieveVaultKeyWithPasskey and renewVaultKeyProtection, #authenticationSession is only cleared on the happy path. @noble/ciphers AES-GCM decrypt throws on an authentication-tag mismatch (wrong key / corrupted ciphertext) rather than returning corrupted plaintext, so any decryption failure propagates past the this.#authenticationSession = null assignments, leaving the session active. At that point the WebAuthn challenge has already been consumed and the counter already advanced by #verifyAuthentication, yet the session still holds the old challenge, making it reusable for a subsequent authenticator interaction.

Additional Locations (1)

packages/passkey-controller/src/PasskeyController.ts#L392-L414

^{Reviewed by Cursor Bugbot for commit afe1777. Configure here.}

cursor · 2026-04-16T11:37:55Z

+    key,
+    signature.buffer as ArrayBuffer,
+    data.buffer as ArrayBuffer,
+  );


RSA Verification Passes Wrong Buffer to Web Crypto

Medium Severity

verifyRSA passes signature.buffer and data.buffer (the raw backing ArrayBuffer) to crypto.subtle.verify instead of the Uint8Array views themselves. When @levischuck/tiny-cbor returns the attestation sig field as a subarray view into the decoded CBOR buffer (common for CBOR libraries to avoid copies), .buffer spans the entire CBOR payload rather than just the signature bytes. Web Crypto then tries to verify using all those extra bytes, causing RSA packed-attestation signature verification to always return false.

Additional Locations (1)

packages/passkey-controller/src/webauthn/decodeAttestationObject.ts#L14-L16

^{Reviewed by Cursor Bugbot for commit afe1777. Configure here.}

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

There are 4 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6f7b1c7. Configure here.}

cursor · 2026-04-17T02:45:24Z

+  const derivationMethod = prfEnabled ? 'prf' : 'userHandle';
+  const ikm: Uint8Array =
+    derivationMethod === 'prf'
+      ? base64URLToBytes(prfFirst as string)


PRF enabled without results crashes key derivation

High Severity

The prfEnabled check uses prf?.enabled === true as a standalone sufficient condition via OR (||). Per the WebAuthn spec, during registration authenticators commonly return {prf: {enabled: true}} without results.first to indicate PRF support. In this case, prfFirst is undefined, prfEnabled evaluates to true, derivationMethod becomes 'prf', and base64URLToBytes(prfFirst as string) crashes with a TypeError when calling .replace() on undefined. The check needs to also require that prfFirst is actually present and non-empty before selecting the PRF derivation path.

^{Reviewed by Cursor Bugbot for commit 6f7b1c7. Configure here.}

cursor · 2026-04-17T02:45:24Z

+  result.set(first, 0);
+  result.set(second, first.length);
+  return result;
+}


Triplicate byte concatenation utility across webauthn files

Low Severity

Three separate private implementations of Uint8Array concatenation exist: concatUint8Arrays in verifyAuthenticationResponse.ts, an identical concatUint8Arrays in verifyRegistrationResponse.ts, and a variadic concatBytes in verifySignature.ts. These all do the same thing and could be a single shared utility, reducing duplication and maintenance burden.

Additional Locations (2)

packages/passkey-controller/src/webauthn/verifyRegistrationResponse.ts#L283-L289

packages/passkey-controller/src/webauthn/verifySignature.ts#L15-L25

^{Reviewed by Cursor Bugbot for commit 6f7b1c7. Configure here.}

tanguyenvn added 3 commits April 10, 2026 10:27

feat: init passkey controller

271ca41

refactor: passkey controller to return registration and authenticatio…

f56e452

…n options

feat: update configuration of passkeys

47b6bf9

tanguyenvn changed the title ~~Feat/to 540 passkey controller~~ Feat/TO-540: Add passkey controller Apr 10, 2026

tanguyenvn self-assigned this Apr 10, 2026